Python Pakotņu Izplatīšana: Publicēšana PyPI un Versiju Pārvaldība

Python plašā ekosistēma balstās uz milzīgu pakotņu kolekciju, kas ir viegli pieejama caur Python Package Index (PyPI). Šis ceļvedis sniedz visaptverošu pārskatu par to, kā izplatīt savas Python pakotnes, izmantojot PyPI, nodrošinot, ka tās ir pieejamas izstrādātājiem visā pasaulē. Mēs apskatīsim būtiskākos rīkus, labāko praksi versiju pārvaldībā un darbplūsmas augstas kvalitātes Python pakotņu izveidei un publicēšanai.

Kāpēc izplatīt savu Python pakotni?

Savas Python pakotnes izplatīšana sniedz daudzas priekšrocības:

• Dalieties ar savu darbu: Ļauj citiem izstrādātājiem viegli atkārtoti izmantot jūsu kodu, veicinot sadarbību un inovācijas. Iedomājieties globālu komandu, kas izmanto jūsu specializētos datu analīzes rīkus, kas izveidoti ar Python.
• Atkarību pārvaldība: Vienkāršo atkarību pārvaldības procesu citos projektos. Jūsu pakotni var instalēt ar vienu komandu, kopā ar visām tās atkarībām.
• Ieguldījums atvērtajā kodā: Ļauj jums dot ieguldījumu atvērtā koda kopienā un gūt atzinību par savu darbu. Daudzas kritiskas programmatūras sastāvdaļas ir atvērtā koda pakotnes, ko uztur izstrādātāji visā pasaulē.
• Versiju kontrole un atjauninājumi: Nodrošina strukturētu veidu, kā pārvaldīt versijas, izlaist atjauninājumus un novērst kļūdas. Tas nodrošina, ka lietotājiem vienmēr ir pieejama jaunākā un uzticamākā jūsu pakotnes versija.
• Viegla instalēšana: Vienkāršo instalēšanu lietotājiem, izmantojot `pip install jusu-pakotnes-nosaukums`.

Būtiskākie rīki Python pakotņu izplatīšanai

Vairāki rīki ir būtiski Python pakotņu izveidei un izplatīšanai:

• setuptools: Plaši izmantota bibliotēka, lai definētu pakotnes metadatus, tostarp nosaukumu, versiju, atkarības un ieejas punktus. Tas ir de facto standarts Python projektu pakošanai.
• wheel: Izplatīšanas formāts, kas nodrošina efektīvāku un uzticamāku instalēšanas procesu salīdzinājumā ar pirmkoda izplatīšanu. “Wheels” ir iepriekš sagatavotas izplatīšanas versijas, kuras var instalēt, neprasot kompilāciju.
• twine: Rīks drošai jūsu pakotnes augšupielādei PyPI. Twine šifrē jūsu akreditācijas datus un pakotnes datus pārraides laikā, aizsargājot pret noklausīšanos un “man-in-the-middle” uzbrukumiem.
• venv/virtualenv: Šie ir rīki izolētu Python vidi izveidei. Virtuālo vidi izmantošana ir ļoti svarīga atkarību pārvaldībai un konfliktu novēršanai starp dažādiem projektiem.

Projekta iestatīšana

Pirms varat izplatīt savu pakotni, jums ir pareizi jāstrukturē savs projekts.

Projekta struktūras piemērs

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

Paskaidrojums:

• my_package/: Galvenais direktorijs, kas satur jūsu pakotnes pirmkodu.
• my_package/__init__.py: Padara `my_package` direktoriju par Python pakotni. Tas var būt tukšs vai saturēt inicializācijas kodu.
• my_package/module1.py, my_package/module2.py: Jūsu Python moduļi, kas satur faktisko kodu.
• tests/: Direktorijs, kas satur jūsu vienības testus. Ir ļoti svarīgi rakstīt testus, lai nodrošinātu jūsu pakotnes kvalitāti un uzticamību.
• README.md: Markdown fails, kas sniedz jūsu pakotnes aprakstu, lietošanas instrukcijas un citu svarīgu informāciju. Tas bieži ir pirmais, ko lietotāji redz PyPI.
• LICENSE: Fails, kas satur licenci, ar kuru jūsu pakotne tiek izplatīta (piemēram, MIT, Apache 2.0, GPL). Atbilstošas licences izvēle ir būtiska, lai norādītu, kā citi var izmantot jūsu kodu.
• setup.py: Galvenais konfigurācijas fails, kas definē jūsu pakotnes metadatus un veidošanas instrukcijas.
• .gitignore: Norāda failus un direktorijus, kurus Git ignorēs (piemēram, pagaidu failus, veidošanas artefaktus).

`setup.py` faila izveide

`setup.py` fails ir jūsu pakotnes izplatīšanas sirds. Tas satur metadatus par jūsu pakotni un instrukcijas tās veidošanai un instalēšanai. Lūk, piemērs:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # Aizstājiet ar savu pakotnes nosaukumu
    version="0.1.0",
    author="Jūsu Vārds",  # Aizstājiet ar savu vārdu
    author_email="jusu.epasts@example.com", # Aizstājiet ar savu e-pastu
    description="Neliels piemēra pakotne",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package", # Aizstājiet ar savu repozitorija URL
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # Piemēra atkarība
    ],
)

Paskaidrojums:

• name: Jūsu pakotnes nosaukums, kas tiks izmantots PyPI. Izvēlieties unikālu un aprakstošu nosaukumu.
• version: Jūsu pakotnes versijas numurs. Sekojiet semantiskajai versiju noteikšanai (skatīt zemāk).
• author, author_email: Jūsu vārds un e-pasta adrese.
• description: Īss jūsu pakotnes apraksts.
• long_description: Garāks, detalizētāks apraksts, parasti nolasīts no jūsu `README.md` faila.
• long_description_content_type: Norāda jūsu garā apraksta formātu (piemēram, "text/markdown").
• url: Jūsu pakotnes mājaslapas URL (piemēram, GitHub repozitorijs).
• packages: Pakotņu saraksts, kas jāiekļauj jūsu izplatīšanā. `setuptools.find_packages()` automātiski atrod visas pakotnes jūsu projektā.
• classifiers: Metadati, kas palīdz lietotājiem atrast jūsu pakotni PyPI. Izvēlieties atbilstošus klasifikatorus no Trove Classifiers saraksta. Apsveriet iespēju iekļaut klasifikatorus atbalstītajām Python versijām, operētājsistēmām un licencēm.
• python_requires: Norāda minimālo Python versiju, kas nepieciešama, lai izmantotu jūsu pakotni.
• install_requires: Atkarību saraksts, kuras jūsu pakotnei ir nepieciešamas. Šīs atkarības tiks automātiski instalētas, kad tiks instalēta jūsu pakotne.

Versiju pārvaldība: Semantiskā versiju noteikšana

Semantiskā versiju noteikšana (SemVer) ir plaši pieņemta versiju shēma, kas nodrošina skaidru un konsekventu veidu, kā paziņot par izmaiņu raksturu jūsu pakotnē.

SemVer versijas numurs sastāv no trīs daļām: MAJOR.MINOR.PATCH.

• MAJOR: Tiek palielināts, kad veicat nesaderīgas API izmaiņas. Tas norāda uz būtiskām izmaiņām, kas var prasīt lietotājiem atjaunināt savu kodu.
• MINOR: Tiek palielināts, kad pievienojat funkcionalitāti atpakaļsaderīgā veidā. Tas apzīmē jaunas funkcijas vai uzlabojumus, kas nesalauž esošo kodu.
• PATCH: Tiek palielināts, kad veicat atpakaļsaderīgus kļūdu labojumus. Tas ir paredzēts nelieliem labojumiem, kas nepievieno jaunas funkcijas un nesalauž esošo funkcionalitāti.

Piemēri:

• 1.0.0: Sākotnējā izlaišana.
• 1.1.0: Pievienota jauna funkcija, nesalaužot esošo kodu.
• 1.0.1: Izlabota kļūda 1.0.0 versijā.
• 2.0.0: Veiktas nesaderīgas API izmaiņas.

SemVer izmantošana palīdz lietotājiem saprast jaunināšanas uz jaunu jūsu pakotnes versiju ietekmi.

Pakotnes veidošana

Kad jūsu `setup.py` fails ir konfigurēts, varat veidot savu pakotni.

1. Izveidojiet virtuālo vidi: Ir ļoti ieteicams izveidot virtuālo vidi, lai izolētu jūsu pakotnes atkarības. Izmantojiet `python3 -m venv .venv` (vai `virtualenv .venv`) un pēc tam to aktivizējiet (`source .venv/bin/activate` Linux/macOS, `.venv\Scripts\activate` Windows).
2. Instalējiet veidošanas atkarības: Palaidiet `pip install --upgrade setuptools wheel`.
3. Veidojiet pakotni: Palaidiet `python setup.py sdist bdist_wheel`. Šī komanda izveido divus izplatīšanas failus `dist` direktorijā: pirmkoda izplatīšanu (sdist) un “wheel” izplatīšanu (bdist_wheel).

`sdist` satur jūsu pirmkodu un `setup.py` failu. `bdist_wheel` ir iepriekš sagatavota izplatīšanas versija, kuru var instalēt ātrāk.

Pakotnes publicēšana PyPI

Pirms varat publicēt savu pakotni, jums ir jāizveido konts PyPI (https://pypi.org/) un jāizveido API marķieris (token). Šis marķieris tiks izmantots, lai autentificētu jūsu augšupielādes.

1. Reģistrējieties PyPI: Ejiet uz https://pypi.org/account/register/ un izveidojiet kontu.
2. Izveidojiet API marķieri: Ejiet uz https://pypi.org/manage/account/, ritiniet uz leju līdz sadaļai "API tokens" un izveidojiet jaunu marķieri. Glabājiet šo marķieri droši, jo jums to vajadzēs, lai augšupielādētu savu pakotni.
3. Instalējiet Twine: Palaidiet `pip install twine`.
4. Augšupielādējiet savu pakotni: Palaidiet `twine upload dist/*`. Jums tiks lūgts ievadīt lietotājvārdu (__token__) un paroli (API marķieris, ko izveidojāt).

Svarīga drošības piezīme: Nekad nepievienojiet savu API marķieri repozitorijam. Glabājiet to droši un izmantojiet vides mainīgos vai citas drošas metodes, lai tam piekļūtu augšupielādes procesā.

Pakotnes instalācijas testēšana

Pēc pakotnes publicēšanas ir svarīgi pārbaudīt, vai to var pareizi instalēt.

1. Izveidojiet jaunu virtuālo vidi: Tas nodrošina, ka jūs testējat instalāciju tīrā vidē.
2. Instalējiet savu pakotni: Palaidiet `pip install jusu-pakotnes-nosaukums`.
3. Importējiet un izmantojiet savu pakotni: Python interpretatorā importējiet savu pakotni un pārbaudiet, vai tā darbojas, kā paredzēts.

Nepārtrauktā integrācija un nepārtrauktā piegāde (CI/CD)

Lai automatizētu pakotnes veidošanas, testēšanas un publicēšanas procesu, varat izmantot CI/CD rīkus, piemēram, GitHub Actions, GitLab CI vai Travis CI.

Lūk, piemērs GitHub Actions darbplūsmai, kas veido un publicē jūsu pakotni PyPI:

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Build package
      run: python setup.py sdist bdist_wheel
    - name: Publish package to PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

Paskaidrojums:

• Šī darbplūsma tiek aktivizēta, kad GitHub tiek publicēta jauna izlaišana.
• Tā pārbauda kodu, iestata Python, instalē atkarības, veido pakotni un augšupielādē to PyPI.
• secrets.PYPI_API_TOKEN ir GitHub noslēpums, kurā tiek glabāts jūsu PyPI API marķieris. Jums ir jākonfigurē šis noslēpums savā GitHub repozitorija iestatījumos.

Labākā prakse Python pakotņu izplatīšanā

• Rakstiet visaptverošu dokumentāciju: Iekļaujiet detalizētu `README.md` failu, kā arī API dokumentāciju, izmantojot tādus rīkus kā Sphinx. Skaidra un pilnīga dokumentācija ir ļoti svarīga, lai padarītu jūsu pakotni viegli lietojamu.
• Rakstiet vienības testus: Rūpīgi pārbaudiet savu kodu, lai nodrošinātu tā kvalitāti un uzticamību. Izmantojiet testēšanas ietvaru, piemēram, pytest vai unittest.
• Sekojiet PEP 8 stila vadlīnijām: Ievērojiet Python Enhancement Proposal 8 (PEP 8) stila rokasgrāmatu, lai nodrošinātu konsekventu un lasāmu kodu.
• Izmantojiet licenci: Izvēlieties atbilstošu atvērtā koda licenci, lai norādītu, kā citi var izmantot jūsu kodu.
• Uzturiet savas atkarības atjauninātas: Regulāri atjauniniet savas pakotnes atkarības, lai gūtu labumu no kļūdu labojumiem, drošības ielāpiem un jaunām funkcijām.
• Izmantojiet virtuālo vidi: Vienmēr izstrādājiet un testējiet savu pakotni virtuālā vidē, lai izolētu atkarības.
• Apsveriet internacionalizāciju (i18n) un lokalizāciju (l10n): Ja jūsu pakotne apstrādā lietotājiem redzamu tekstu vai datus, apsveriet iespēju to pielāgot dažādām valodām un reģioniem. Tas paplašina jūsu potenciālo lietotāju bāzi visā pasaulē. Tādi rīki kā Babel var palīdzēt šajā jautājumā.
• Apstrādājiet dažādas laika joslas un valūtas: Ja jūsu pakotne strādā ar datumiem, laikiem vai finanšu darījumiem, esiet uzmanīgi attiecībā uz dažādām laika joslām un valūtām visā pasaulē. Izmantojiet atbilstošas bibliotēkas un API, lai pareizi apstrādātu šīs sarežģītības.
• Sniedziet skaidrus kļūdu paziņojumus: Rakstiet informatīvus kļūdu paziņojumus, kas palīdz lietotājiem saprast, kas nogāja greizi un kā to labot. Ja iespējams, tulkojiet šos kļūdu paziņojumus dažādās valodās.
• Domājiet par pieejamību: Izstrādājot savas pakotnes saskarni un dokumentāciju, ņemiet vērā lietotājus ar invaliditāti. Ievērojiet pieejamības vadlīnijas, lai nodrošinātu, ka jūsu pakotne ir lietojama visiem.

Padziļinātas tēmas

• Nosaukumvietu pakotnes: Ļauj sadalīt vienu Python pakotni vairākos direktorijos vai pat vairākās izplatīšanas versijās.
• Ieejas punkti: Ļauj definēt funkcijas vai klases, kuras var izsaukt no citām pakotnēm vai no komandrindas.
• Datu faili: Ļauj iekļaut ne-Python failus (piemēram, datu failus, konfigurācijas failus) savā izplatīšanā.
• Nosacījuma atkarības: Ļauj norādīt atkarības, kas ir nepieciešamas tikai noteiktos apstākļos (piemēram, noteiktā operētājsistēmā).

Noslēgums

Savas Python pakotnes izplatīšana PyPI ir lielisks veids, kā dalīties ar savu darbu ar pasauli un dot ieguldījumu Python ekosistēmā. Sekojot šajā ceļvedī aprakstītajiem soļiem un labākajai praksei, jūs varat izveidot un publicēt augstas kvalitātes Python pakotnes, kuras ir viegli instalēt, lietot un uzturēt. Atcerieties par prioritāti noteikt skaidru dokumentāciju, rūpīgu testēšanu un konsekventu versiju pārvaldību, lai nodrošinātu jūsu pakotnes panākumus.